home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / hdf / docs / hdfvset.lha / HDFVset.ch6 < prev    next >
Encoding:
Text File  |  1994-01-10  |  11.0 KB  |  593 lines
  1.  
  2.  
  3.  
  4. HDF Vset FORTRAN Interface    6.1
  5.  
  6.  
  7.  
  8.  
  9. November 1990
  10.  
  11.                                                                 
  12.  
  13.  
  14.  
  15.  
  16.  
  17. 6.1    NCSA HDF Vset
  18.  
  19.  
  20. National Center for Supercomputing Applications
  21.  
  22.  
  23. November 1990
  24.  
  25.  
  26.  
  27.  
  28.  
  29. Chapter  6    HDF Vset FORTRAN Interface
  30.  
  31.  
  32.  
  33. Chapter Overview
  34. Vgroup Level Calls
  35. Vdata Level Calls
  36. Vgroup FORTRAN Routines
  37. VFATCH
  38. VFDTCH
  39. VFGCLS
  40. VFGID
  41. VFGNAM
  42. VFGNXT
  43. VFINQ
  44. VFINSRT
  45. VFISVG
  46. VFISVS
  47. VFLONE
  48. VFSCLS
  49. VFSNAM
  50. Vdata FORTRAN Routines
  51. VSFATCH
  52. VSFDTCH
  53. VSFFDEF
  54. VSFEX
  55. VSFGCLS
  56. VSFGID
  57. VSFGNAM
  58. VSFINQ
  59. VSFLONE
  60. VSFREAD
  61. VSFSCLS
  62. VSFSEEK
  63. VSFSFLD
  64. VSFSINT
  65. VSFSNAM
  66. VSFWRIT
  67. FORTRAN Example
  68.  
  69. Chapter Overview
  70.  
  71. This chapter briefly discusses the vgroup and vdata routines 
  72. available for use with FORTRAN. In the three succeeding tables 
  73. below, use the function names in the first column in FORTRAN 
  74. applications.
  75.  
  76.  
  77. Vgroup Level Calls
  78. Name    C equivalent
  79.  
  80. VFATCH    (f, vsid, access)    Vattach 
  81. VFDTCH    (vg)    Vdetach
  82. VFGCLS    (vg, vgclass)    Vgetclass
  83. VFGID    (f, vgid)    Vgetid
  84. VFGNAM    (vg, vgname)    Vgetname
  85. VFGNXT    (vg, id)    Vgetnext
  86. VFINQ    (vg, nentries, vgname)    Vinquire
  87. VFINSRT    (vg, vs)    Vinsert
  88. VFISVG    (vg, id)    Visvg
  89. VFISVS    (vg, id)    Visvs
  90. VFLONE    (f, idarray, asize)    Vlone
  91. VFSCLS    (vg, vgclass)    Vsetclass
  92. VFSNAM    (vg, vgname)    Vsetname
  93.  
  94.  
  95. Vdata Level Calls
  96. Name    C equivalent
  97.  
  98. VSFATCH    (f, vsid, access)    VSattach
  99. VSFDTCH    (vs)    VSdetach
  100. VSFFDEF    (vs, field, fieldtype, order)    VSfdefine
  101. VSFEX    (vs, fields)    VSfexist
  102. VSFGCLS    (vs, vsclass)    VSgetclass
  103. VSFGID    (f, vsid)    VSgetid
  104. VSFGNAM    (vs, vsname)    VSgetname
  105. VSFINQ    (vs, nelements, interlace,
  106.     fields, vsize, vsname)    VSinquire
  107. VFSLONE    (f, idarray, asize)    VSlone
  108. VSFREAD    (vs, buf, nelements, interlace)    VSread
  109. VSFSCLS    (vs, vsclass)    VSsetclass
  110. VSFSEEK    (vs, element)    VSseek
  111. VSFSFLD    (vs, fields)    VSsetfields
  112. VSFSINT    (vs, interlace)    VSsetinterlace
  113. VSFSNAM    (vs, vsname)    VSsetname
  114. VSFWRIT    (vs, buf, nelements, interlace)    VSwrite
  115.  
  116.  
  117.  
  118. Vgroup FORTRAN Routines
  119.  
  120. The following section briefly describes the vgroup routines 
  121. available for use in FORTRAN. The FORTRAN routines appear 
  122. in the right-hand column. Refer to Chapter 4, "Vgroup Routine 
  123. Descriptions," for a more detailed discussion of these routines.
  124.  
  125.  
  126. VFATCH 
  127. integer function VFATCH  (f,vsid,access)
  128.  
  129. integer     f
  130. integer     vsid
  131. character*1    access     ('r' or 'w')
  132.  
  133. Purpose:  Attaches to a vgroup.
  134.  
  135. Return value:  Upon success, id of the vgroup (positive integer); 
  136. otherwise, -1 .
  137.  
  138.  
  139. VFDTCH
  140. subroutine VFDTCH  (vg)
  141.  
  142. integer    vg
  143.  
  144. Purpose:  Detaches a vgroup.
  145.  
  146. Return value:  None.
  147.  
  148.  
  149. VFGCLS
  150. subroutine VFGCLS   (vg, vgclass)
  151.  
  152. integer        vg
  153. character*(*)    vgclass
  154.  
  155. Purpose: Returns the class name of the vgroup.
  156.  
  157. Return value: None.
  158.  
  159.  
  160. VFGID
  161. integer function VFGID   (f,vgid)
  162.  
  163. integer    f
  164. integer    vgid
  165.  
  166. Purpose:  Returns the id of the next vgroup in the file.
  167.  
  168. Return value:  Upon success, id of next vgroup (0 or positive 
  169. integer); otherwise, -1.
  170.  
  171.  
  172. VFGNAM
  173. subroutine VFGNAM   (vg,vgname)
  174.  
  175. integer        vg
  176. character*(*)    vgname
  177.  
  178. Purpose:  Returns the name of a vgroup.
  179.  
  180. Return value:  None.
  181.  
  182. VFGNXT
  183. integer function VFGNXT   (vg,id)
  184.  
  185. integer    vg
  186. integer    id
  187.  
  188. Purpose:  Returns the id of the next entry from the vgroup.
  189.  
  190. Return value:  Upon success, id of next entry (0 or positive integer); 
  191. otherwise, -1.
  192.  
  193.  
  194. VFINQ
  195. integer function VFINQ   (vg,nentries,vgname)
  196.  
  197. integer        vg
  198. integer        nentries
  199. character*(*)    vgname
  200.  
  201. Purpose:  Performs a general inquiry on a vgroup.
  202.  
  203. Return value:  Upon success, 1; otherwise, -1.
  204.  
  205.  
  206. VFINSRT
  207. integer function VFINSRT   (vg,v)
  208.  
  209. integer    vg
  210. integer    v      
  211.  
  212. Purpose:  Inserts a vgroup or vdata to the given vgroup.
  213.  
  214. Return value:  Upon success, the position in vgroup where entry is 
  215. inserted (0 or positive integer); if error, -1.
  216.  
  217.  
  218. VFISVG
  219. integer function VFISVG   (vg, id)
  220.  
  221. integer     vg
  222. integer    id
  223.  
  224. Purpose:   Determines if an id in a vgroup refers to a vgroup.
  225.  
  226. Return value:  If it refers to a vgroup, 1; otherwise 0.
  227.  
  228.  
  229. VFISVS
  230. integer function VFISVS   (vg, id)
  231.  
  232. integer     vg
  233. integer    id
  234.  
  235. Purpose:  Determines if an id in a vgroup refers to a vdata.
  236.  
  237. Return value:  If it refers to a vdata, 1; otherwise 0.
  238.  
  239.  
  240. VFLONE
  241. integer function VFLONE   (f, idarray, asize)
  242.  
  243. integer    f
  244. integer    idarray(*)
  245. integer    asize
  246.  
  247. Purpose: Returns an array of reference numbers of vgroups that 
  248. are not linked to any other vgroup. 
  249.  
  250. Return value: Upon success, the total number of such vgroups in the 
  251. file; otherwise, -1.
  252.  
  253.  
  254. VFSCLS
  255. subroutine VFSCLS   (vg, vgclass)
  256.  
  257. integer        vg
  258. character*(*)    vgclass
  259.  
  260. Purpose: Sets the class name for the vgroup.
  261.  
  262. Return value: None.
  263.  
  264.  
  265. VFSNAM
  266. subroutine VFSNAM   (vg,vgname)
  267.  
  268. integer        vg
  269. character*(*)    vgname
  270.         
  271. Purpose:  Sets the name of the vgroup.
  272.  
  273. Current limitation:  The name string cannot contain blank 
  274. spaces.
  275.  
  276. Return value:  None.
  277.  
  278.  
  279. Vdata FORTRAN Routines
  280.  
  281. The following section briefly describes the vdata routines 
  282. available for use in FORTRAN. Refer to Chapter 5, "Vdata 
  283. Routine Descriptions," for a more detailed discussion of these 
  284. routines.
  285.  
  286.  
  287. VSFATCH
  288. integer function VSFATCH   (f,vsid,access)
  289.  
  290. integer         f
  291. integer         vsid
  292. character*(1)    access ('r' or 'w')
  293.  
  294. Purpose:   Attaches to a vdata.
  295.  
  296. Return value:  Upon success, id of vdata (positive integer); 
  297. otherwise, -1 .
  298.  
  299.  
  300. VSFDTCH
  301. subroutine VSFDTCH   (vs)
  302.  
  303. integer    vs
  304.  
  305. Purpose:  Detaches from a vdata.
  306.  
  307. Return value:  None.
  308.  
  309.  
  310. VSFFDEF
  311. integer function VSFFDEF   (vs,field,fieldtype, 
  312. order)
  313.  
  314. integer        vs
  315. character*(*)    field
  316. integer        fieldtype
  317. integer        order
  318.  
  319. Purpose:   Defines a new field to be used in the vdata.
  320.  
  321. Return value:  Upon success, 1; otherwise, -1.
  322.  
  323.  
  324. VSFEX
  325. integer function VSFEX   (vs,fields)
  326.  
  327. integer        vs
  328. character*(*)    fields
  329.  
  330. Purpose:  Tests if given fields exist in the data.
  331.  
  332. Return value:  If the field(s) exist, 1; otherwise, -1
  333.  
  334.  
  335. VSFGCLS
  336. subroutine VSFGCLS   (vs, vsclass)
  337.  
  338. integer        vs
  339. character*(*)    vsclass
  340.  
  341. Purpose: Returns the class name of the vdata.
  342.  
  343. Return value: None.
  344.  
  345.  
  346. VSFGID
  347. integer function VSFGID   (f,vsid)
  348.  
  349. integer    f
  350. integer    vsid
  351.  
  352. Purpose:  Returns the id of the next vdata from the file.
  353.  
  354. Return value:  Upon success, id of vdata (0 or positive integer); 
  355. otherwise, -1 if error or no more vdatas exist.
  356.  
  357.  
  358. VSFGNAM
  359. subroutine VSFGNAM   (vs,vsname)
  360.  
  361. integer        vs
  362. character*(*)    vsname
  363.  
  364. Purpose:  Returns the name of the vdata.
  365.  
  366. Return value:  None.
  367.  
  368.  
  369. VSFINQ
  370. integer function VSFINQ 
  371. (vs,nelements,interlace,fields,vsize,vsname)
  372.  
  373. integer        vs
  374. integer        nelements
  375. integer        interlace
  376. integer        vsize
  377. character*(*)    fields
  378. character*(*)    vsname
  379.  
  380. Purpose:  Performs a general inquiry on the vdata.
  381.  
  382. Return value:  If the vdata is ok, 1 is returned; if an error exists, -1 
  383. is returned.
  384. VSFLONE
  385. integer function VSFLONE   (f, idarray, asize)
  386.  
  387. integer    f
  388. integer    idarray(*)
  389. integer    asize
  390.  
  391. Purpose: Returns an array of reference numbers of vdatas that are 
  392. not linked to any other vgroup.
  393.  
  394. Return value: Upon success, the total number of such vdatas in the 
  395. file; otherwise, -1.
  396.  
  397.  
  398. VSFREAD
  399. integer function VSFREAD   (vs,buf,nelements, 
  400. interlace)
  401.  
  402. integer        vs
  403. character*(*)    buf
  404. integer        nelements
  405. integer        interlace
  406.  
  407. Purpose:  Reads from a vdata.
  408.  
  409. Return value:  Upon success, the number of elements read (positive 
  410. integer); otherwise, -1.
  411.  
  412.  
  413. VSFSCLS
  414. subroutine VSFSCLS   (vs, vsclass)
  415.  
  416. integer        vs
  417. character*(*)    vsclass
  418.  
  419. Purpose: Sets the class name for the vdata.
  420.  
  421. Return value: None.
  422.  
  423.  
  424. VSFSEEK
  425. integer function VSFSEEK   (vs, element)
  426.  
  427. integer    vs
  428. integer    element
  429.  
  430. Purpose:  Moves to an element's location in a vdata.
  431.  
  432. Return value:  Upon success, the element number (0 or positive 
  433. integer); otherwise, -1
  434.  
  435.  
  436. VSFSFLD
  437. integer function VSFSFLD   (vs, fields)
  438.  
  439. integer        vs
  440. character*(*)    fields        
  441.  
  442. Purpose:  Sets the fields in a vdata for reading or writing.
  443.  
  444. Return value:  Upon success, 1; otherwise, -1.
  445.  
  446.  
  447. VSFSINT
  448. subroutine VSFSINT   (vs,interlace)
  449.  
  450. integer    vs
  451. integer    interlace
  452.  
  453. Purpose:  Sets the file interlace for a vdata.
  454.  
  455. Return value:  Upon success, 1; otherwise, -1.
  456.  
  457. VSFSNAM
  458. subroutine VSFSNAM   (vs,vsname)
  459.  
  460. integer        vs
  461. character*(*)    vsname
  462.         
  463. Purpose:  Sets the name of the vdata.
  464.  
  465. Current limitation:  vsname cannot contain blank spaces.
  466.  
  467. Return value:  None.
  468.  
  469.  
  470. VSFWRIT
  471. integer function VSFWRIT   (vs, buf, nelements, 
  472. interlace)
  473.  
  474. integer        vs
  475. character*(*)    buf
  476. integer        nelements
  477. integer        interlace
  478.  
  479. Purpose:  Writes to a vdata.
  480.  
  481. Return value:  Upon success, the number of elements 
  482. written(positive integer); otherwise, -1.
  483.  
  484.  
  485. FORTRAN Example
  486.  
  487. Figure 6.1 shows an example FORTRAN program which stores a 
  488. dataset as a vset of one vgroup and two vdatas.
  489.  
  490. Figure 6.1     FORTRAN 
  491. Example
  492.  
  493. c      =================================================================
  494. c
  495. c       EG1.F
  496. c       HDF VSET Sample Program
  497. c
  498. c       Creates a vset of 1 vgroup and 2 vdatas into the file 'eg1.hdf'.
  499. c
  500. c       compile and link
  501. c       compile to get the object file 'eg1.o'
  502. c       link 'eg1.o' with the libraries 'libvg.a' and 'libdf.a'
  503. c
  504. c       What this program do: step by step.
  505. c
  506. c       --- (A) ----
  507. c       --- open HDF file, attach to new vgroup
  508. c       --- name the vgroup 'my_fortran_vgroup'
  509. c
  510. c       --- (B) ----
  511. c       --- attach to new (1st) vdata, name it 'the_fortune_500_vdata'
  512. c       --- write out 20 integers from buf as the predefined field 'IY'
  513. c       --- tell VSFWRIT your data is fully-interlaced.
  514. c       --- insert the vdata into the above vgroup
  515. c       --- when done, detach the vdata.
  516. c
  517. c       --- (C) ---
  518. c       --- attach to new (2nd)  vdata, name it 'the-famous-sevens'
  519. c       --- define your own new field 'SIEBEN' type integer.
  520. c       --- write out 70 integers from buf as the field 'SIEBEN'
  521. c       --- tell VSFWRIT your data is fully-interlaced.
  522. c       --- insert the vdata into the above vgroup
  523. c       --- when done, detach the vdata.
  524. c
  525. c       --- (D) ---
  526. c       --- finally detach the vgroup and close the file
  527. c      =================================================================
  528.  
  529.         program SAMPLE
  530.  
  531.         integer buf(100), sbuf(100), i,n
  532.         integer f
  533.  
  534.         external DFOPEN, DFCLOSE
  535.         external VSFATCH, VSFDTCH, VSFSFLD, VSFSNAM, VSFWRIT
  536.         external VSFFDEF
  537.         external VFATCH, VFDTCH, VFSNAM, VFINSRT
  538.         integer  DFOPEN
  539.         integer  VSFATCH, VSFSFLD, VSFWRIT, VSFFDEF
  540.         integer  VFATCH, VFINSRT
  541.  
  542.         integer  vs, vg
  543.  
  544. c       some defined constants. see "vg.h"
  545.         integer INTTYPE
  546.         parameter (INTTYPE=2)
  547.  
  548. Figure 6.1     FORTRAN Example (Continued)
  549.  
  550.         integer FINTRLACE
  551.         parameter (FINTRLACE=0)
  552.  
  553.         integer FULLACC
  554.         parameter (FULLACC=7)
  555.  
  556. c       ------ generate data -------
  557.         do 111 i=1,100
  558.                 buf(i) = i+500
  559.                 sbuf(i) = i+7000
  560. 111     continue
  561.  
  562.  
  563. c       ------ write to vset -------
  564.  
  565. c       --- (A) ----
  566.         f = DFOPEN ('eg1.hdf', FULLACC, 0)
  567.         vg = VFATCH (f, -1,'w')
  568.         call VFSNAM(vg, 'my_fortran_group')
  569.  
  570. c       --- (B) ----
  571.         vs = VSFATCH (f, -1,'w')
  572.         call VSFSNAM(vs, 'the_fortune_500_vdata')
  573.         n = VSFSFLD (vs, 'IY')
  574.         n = VSFWRIT (vs, buf,20, FINTRLACE)
  575.         n = VFINSRT (vg, vs)
  576.         call VSFDTCH (vs)
  577.  
  578. c       --- (C) ---
  579.         vs = VSFATCH (f, -1,'w')
  580.         call VSFSNAM(vs, 'the-famous-sevens')
  581.         n = VSFFDEF (vs, 'SIEBEN',INTTYPE,1)
  582.         n = VSFSFLD (vs, 'SIEBEN')
  583.         n = VSFWRIT (vs, sbuf,70, FINTRLACE)
  584.         n = VFINSRT (vg, vs)
  585.         call VSFDTCH (vs)
  586.  
  587. c       --- (D) ---
  588.         call VFDTCH (vg)
  589.         call DFCLOSE (f)
  590.  
  591.         end
  592.  
  593.